		BeApple][

Yet another useless software.
Apple ][+ emulator for BeOS

	version  0.2.0

	This software emulates an Apple ][+ computer with 2 disk drives, the 16kB language card and a color display. There is also a little joystick emulation and a quite audible speaker.

1.Using Emulator

1.1 Installation
	The emulator requires the following files in the same directory :
	-BeAppleII executable
	-Apple2.rom : Original Apple computer ROM ( same as AppleWin's)
	-character.rom : character generator.
	-Some disk image files.
 It also uses a "EmulatorAppleII_settings" file in the /home/config/settings directory. Uninstalling can be done by wipping off all these files.

1.2. Why another emulator ?
	I know that many briliant emulators are available for the Apple ][ computer, I have also heard of an emulator running on BeBoxes, as well as 'Sweet16'. This one do not pretend being better than others, and was designed as a challenging first BeOS programming exercise. This emulator is NOT a port of any preexisting one.
- Free software.
- No assembly langage ( it is thus quite slow comparing to many others ). It should work fine on PowerPC computers.
- Quite user-friendly.
- Maybe the best speaker emulation.

	Well, do I mean that you need a >100MHz processor to emulate a poor old 1MHz 6502... Yes, that's it. A 300MHz computer works fine with 8MHz emulation.

1.3. Disk Drives
	As the original Apple ][ 5 1/4 disks uses a uncommon format, they cannot be read by any conventionnal floppy disk controller as in P.C., Atari,  ... Disks are converted to disks images which are stored on the hard drive. This emulator can read 2 kinds of disk images :
DSK : Standard DOS 3.3 disk images :
	256bytes*16sectors*35tracks=143360bytes
NIB : Low level formatting, used for copy-protected software
	6656bytes*35tracks=232960bytes (Note : 4µs/bit, 300rpm -> 5turns/second -> 50000 bits / track 'theorical')
	You select disk images using the Drive buttons. All the selected images are placed in the menu button under. You can also drag & drop files to the screen view ; the dropped files will appear in the Drive 1 slot.
	The tiny blue line represents the position of the head of the disk drive.
FOR NOW, THERE IS NO DISK PROTECTION DETECTION. NOTHING PREVENTS THE EMULATOR FROM CLOBBERING YOUR IMAGE FILES. COPY ALL YOUR DISK IMAGES BEFORE FEEDING THEM TO THIS EMULATOR ( I never had any problem, but now, you are warned ).
	Nothing prevents you from selecting another disk image while the disk drive is running. Like any "real" computer, it can produce impredictable results, including the alteration of both disk images.
	The disk image files are not locked : They are read to memory when you select them and updated ( when necessary ) when you shut down your emulator or select another disk image.
	How can I create a fresh new disk image ? To create a new DOS order disk, copy an existing one ( like 'sample.dsk' in the archive ) to a new file and type 'INIT HELLO', Apple][ users may remind this.

1.4. Cassette Tapes

	Reading
	In addition to optional disk drives, the Apple ][ computers could store programs on tapes. It is obviously much less efficient than disk drives. To use it, first get a sound file containing a recording of that tape, then :
	- Start BeApple][
	- Press RESET ( Alt R ) button.
	- Type 'LOAD'
	- Open the file using the 'Load Tape' ( Alt T )
	- Press RETURN ( You have approximatively 5 seconds to do it )
	- Wait. If you set the normal CPU speed, it will last as long as the original tape. Note that you can select an higher speed.
	- Type 'RUN' RETURN
	 Notes : 
	- A sample tape is available on BeBits and on 'www.chez.com/treza/beapple2.html', in a separate archive.
	- A 8kB program will last approximatively 1min 30sec recording. If you use the standard SoundRecorder application, at 44.1kHz / 16bits / stereo, the sound file will be as big as 15MB. With MP3 compression, it will drop to 350kB, which is still quite big for a 8kB program !

	Writing
	Select 'Save Tape' ( Alt S ) to begin and stop recording. Depending on the 'Speaker Out' and 'Tape Out' configuration checkboxes, the generated file will contain sound from the speaker, from the tape output or from both. To get audible music and 'reloadable' tapes, select the normal CPU speed, i.e. 1MHz.

	Indicators
	Two shapes are visible when the screen is Zoomed. The -green- triangle indicates that a tape is playing. The -red- rectangle indicates that a tape is recording.

1.5. Freezer
	There is a freeze/unfreeze state option which saves into a file the exact state of the emulated CPU ( memory, registers, graphic modes ... ). Only the currently selected disk image and the name of the disk images are archived, not all the disk images, take care of keeping them at the same place. That feature can be very useful for saving games at any moment.
	Frozen state files use a special format which is not related to .DSK and .NIB files.

	The Configuration panel options ( CPU speed, Monitor type, ... ) are not archived in the frozen state file, they are kept in the EmulatorAppleII_settings file instead.

1.6. Keyboard & Menus

File
	Alt-1 : Disk 1 button
		Select Disk 1 images.
	Alt-2 : Disk 1 button
		Select Disk 2 images.
	Alt-T : Load tape
		Select the sound file to be used as tape input.
	Alt-S : Save tape
		Select the name of the sound file that will be generated.
	F5/F6
		Navigate through selected disk images, Disk 1
	F7/F8
		Navigate through selected disk images, Disk 2
	Alt-F
		Freeze state
	Alt-U
		Unfreeze state
	Alt-A
		About. Every sorftware shold have an About box.
	Alt-Q
		Quit. Because you cannot play forever.
Control
	Alt-R : Reset button
		Warm Reset, like pressing the Reset key.
	Alt-I : Init button
		Initialise : Like switching off then on the computer
		So, pressing Reset stops programs, whereas Init clears memory and everything else.
	Alt-M
		Selects the Mouse for Joystick emulation.  Moving the mouse onto the screen window moves the emulated joystick.
	Alt-J
		Selects the Joystick for Joystick emulation. The emulator uses the first available joystick on your computer. Take care of its calibration using the BeOS 'Joysticks' preference panel.

Window
	Alt +
		Zoom in
	Alt -
		Zoom out
	Alt D
		Dump screen to clipboard. To create a real picture file :
			1) Launch 'ShowImage' with a dummy picture.
			2) Do 'Edit/Paste'.
			3) Drag/drop the selected rectangle onto the desktop, or onto any other folder.

Options
	Alt C. Config. button
		Open the Configuration panel.

	Unlike many other emulators, this one does not remap characters, it should work fine on non-qwerty keyboards ( it actually works with my azerty kbd ) but some games uses the position of keys as reference ( like A to go up and Z to go down ), you may need to remap your keyboard to qwerty ( Keymap preference panel ) for better ergonomy.
	The Apple][ keyboard is designed to deliver uppercase caracters, so many Apple][ softwares expect uppercase letters.

1.7 : Configuration
	CPU Speed : Just try to guess.
	Display : Select the display model : Even ugly amber ! The colors are ajusted upon a PAL Apple //e computer. Low resolution graphic mode is not affected by that switch ( alas ).
	Sound filter : The filters remove hi-frequency noise.
	Speaker / Tape Output : To select sound output.
	Joystick : The original joystick interface uses a monostable multivibrator to measure the joystick position. You can choose to trim the delay associated to the full range positon or to use the number of times the Joystick IO adress is accessed to determine the position. If the emulated cursor moves far from your mouse's pointer, try first to toggle this radiobutton before tuning the associated value.
	Turbodisk : Speeds up drive acceses by artificially decreasing the CPU cycle count. As the speed regulator uses that count, the emulation goes faster for a while but the computer is more busy as the instructions are still emulated. Turbodisk may also alter the sound played just after a disk access. (There is no sound during disk accesses )

1.8 : Licencing
	You can use and distribute this software freely.
	I don't know ( and don't want to know ) whether you have the right to use the AppleII firmware ROMs if you don't posess a real Apple ][ computer ( Personally, I have 5, I think it's enough ). I don't know ( and .. .. know ) either you can legally use or not the disk images that can be found on Internet. That software is distributed with the AppleII+ ROMs, because they can be easily found on Internet, because they are included with many other emulators and because you may not posess an EPROM reader to extract the binary code from your genuine AppleII. IT DOES NOT MEAN THAT YOU CAN USE IT !!!
	Again, repeat after me :
	I  WILL NOT USE THESE ROMs WITHOUT POSSESSING A REAL APPLE II COMPUTER OR AN OFFICIAL LICENSE FROM 'Apple Computers Inc.'
	That thing comes with no warranty, you are responsible of all troubles that may occur while using it. As it includes no special driver lever code, if it manages to crash completely your computer, it's Be Inc. fault, not mine ( ;-> ). That software cannot be used in any safety critical apparatus. Available in industrial temperature range ( -40°C to +85°C). Flashing lights may cause on some people epileptic crisis. Using computers may, in some exceptional cases, injure you severely. That software is 100% recyclable when moved to the trash, it does not clobber your system with wild DLLs or hidden files. Did I forgot anything ?

1.8 : Related resources
	- There is a quite efficient tool for transferring disk images. Its name is ADT122 ( Find it on Internet with your favorite search engine ). Alas, you will need an Apple][ computer with a Super Serial card and a MS-DOS or MS-Windows PC computer.

1.9 : To be continued
	I am awaiting your suggestions concerning that software
	Hey, that's not a bug, that's an undocumented feature (UDF).
	If you find strange UDFs, please tell me. 

2. Source code

( Folder Icon blended by IconBlender v0.8 )
-You may use the source code to recompile it on other hardware platforms.
-The source code still needs heavy rewriting.
-You shall not distribute an enhanced version of that software, I am the only maintainer of BeAppleII. You can freely adapt it on other OSes and distribute it as you wish.
-You can include any part of this software in your own creations, you are not supposed to distribute the source code nor to give it freely, with the condition it is not another AppleII emulator for the BeOS.
-If you pick any substantial part of that source code ( more than 30 lines ) you would be kind to tell in the credits paragraph of the online documentation something like : "Includes parts of BeAppleII by O.DANET"
-If you're too stupid to understand the terms above, consider that piece of code as Public Domain.
-It is really fun to write an emulator. You also, you can make your own !

									Avril 2001	O.DANET

			Comments, suggestions, ...	odanet@caramail.com

3. Revision history

	Version 0.2.0 is somewhat better than version 0.1.1 than version 0.1.1 was better comparing to version 0.1.0, basically.

	0.1.0 : ( BeOS R4.0 ) Aout 1999 
		- Initial issue
	0.1.1 : ( BeOS R4.5 ) Mai 2000 
		- Bugfixes
		- Added Zooming
	0.2.0 : ( BeOS R5.0 ) Avril 2001
		- Bugfixes / Revamped sources.
		- Added Joystick support
		- Smoother display... and more CPU load too...
		- Added Tape support
		- Added sound filters
		- Added 'dump screen to clipboard'
		


